home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_2 / issue_06 / arcstuff / arc_doc next >
Encoding:
Text File  |  1988-10-17  |  18.8 KB  |  433 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.           ************************************************************
  9.  
  10.           *                                                          *
  11.  
  12.           *                          Beebug                          *
  13.  
  14.           *                                                          *
  15.  
  16.           *                    A R C H I M E D E S                   *
  17.  
  18.           *                                                          *
  19.  
  20.           *                AA      RRRRRRRR      CCCCCC              *
  21.  
  22.           *              AA  AA    RR      RR  CC      CC            *
  23.  
  24.           *            AA      AA  RR      RR  CC                    *
  25.  
  26.           *            AAAAAAAAAA  RRRRRRRR    CC                    *
  27.  
  28.           *            AA      AA  RR  RR      CC                    *
  29.  
  30.           *            AA      AA  RR    RR    CC      CC            *
  31.  
  32.           *            AA      AA  RR      RR    CCCCCC              *
  33.  
  34.           *                                                          *
  35.  
  36.           *                                                          *
  37.  
  38.           *                     by David Pilling                     *
  39.  
  40.           *                                                          *
  41.  
  42.           *                                                          *
  43.  
  44.           *              This program is Public Domain               *
  45.  
  46.           *                                                          *
  47.  
  48.           ************************************************************
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57. *********************************************************************************                              ARC Version Numbers                             **                              -------------------                             **                                                                              ** Version 1.0 - 29/06/88       Initial release                                 ** Version 1.1 - 01/09/88       PKARC compatibility added                       ** Version 1.2 - 17/10/88       Network compatible version                      **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              ********************************************************************************* Archimedes ARC                                                          Page 2
  58.  
  59.  
  60.  
  61.  
  62.                                   Contents
  63.  
  64.                                   --------
  65.  
  66.  
  67.  
  68.                          (1) Introduction
  69.  
  70.                          (2) How to use ARC
  71.  
  72.                          (3) ARC commands
  73.  
  74.                          (4) Archimedes ARC file format
  75.  
  76.                          (5) ARC support
  77.  
  78.  
  79.  
  80.  
  81. 1. Introduction
  82.  
  83. ---------------
  84.  
  85. ARC is the Archimedes archive utility. An archive is a file in which many 
  86.  
  87. smaller files are stored. You may, using the ARC utility, create archives and 
  88.  
  89. add files to them (ARC'ing a file) or remove files (de-ARC'ing). One of the 
  90.  
  91. features of ARC, is that files are stored in a highly compressed form; thus 
  92.  
  93. saving disc space and allowing more rapid transfer of files by modem. However, 
  94.  
  95. probably the most useful feature of an archive is that like sub-directories 
  96.  
  97. in the ADFS, it makes keeping track of files when transferring them from one 
  98.  
  99. machine to another, much simpler.
  100.  
  101.  
  102. Archives have a long history going back to UNIX and CP/M. An example of an 
  103.  
  104. archive with no compression is the UNIX shar format. Whilst on CP/M archive 
  105.  
  106. utilities which used data compression include squeeze, LUE and LBR. Perhaps 
  107.  
  108. the most well known archive format and utility is the System Enhancements 
  109.  
  110. Associates (SEA) ARC for the IBM PC which was based on many of these earlier 
  111.  
  112. programs. This has now been transferred to the Atari ST and Amiga micros. In 
  113.  
  114. addition, other more advanced versions of it have appeared on the PC like 
  115.  
  116. PKARC by Phil Katz. Beebug Archimedes ARC is fully compatible with SEA's ARC 
  117.  
  118. program. Using it, you can successfully unpack PC archives on your Archimedes, 
  119.  
  120. as well as create PC format archives. In addition, you can use a special 
  121.  
  122. Archimedes format archive which while not compatible with the PC, preserves 
  123.  
  124. Archimedes file attributes like load and exec addresses.
  125.  
  126.  
  127. If you dial up your local bulletin board, you will see many ARC files (they 
  128.  
  129. are usually identified by the suffix .ARC). Using ARC, you will be able to 
  130.  
  131. transfer the files in these to your Archimedes. Obviously, you cannot use 
  132.  
  133. executable PC programs, but there are many text and data files which you may 
  134.  
  135. want to examine (such as documentation, C source files, screen images etc.).
  136.  
  137.  
  138. Do not get the impression from the above, that the data compression aspect of 
  139.  
  140. ARC is just a side effect. Frequently, you may achieve a space saving of upto 
  141.  
  142. 90%. Just how much space you save, depends on the type of file being ARC'd. 
  143.  
  144. Text files usually compress well. Whilst PC executable files rarely compress 
  145.  
  146. by much, Archimedes executables seem to show good savings in space (often 
  147.  
  148. owing to Acorn's way of handling arrays and because of the high redundancy in
  149.  
  150. ARM code).
  151.  
  152. Archimedes ARC                                                          Page 3
  153.  
  154.  
  155.  
  156.  
  157. 2. How to use ARC
  158.  
  159. -----------------
  160.  
  161. Archimedes ARC consists of two files: the program ARC, and ARC_DOC containing 
  162.  
  163. this text. You use ARC by typing *arc followed by a number of parameters. If 
  164.  
  165. you type *arc on its own without parameters, a page of help information is 
  166.  
  167. displayed. For example:
  168.  
  169.  
  170.  
  171.     *arc
  172.  
  173.  
  174.     Archimedes ARC - Archive utility
  175.  
  176.     Usage: ARC {amufdxeplt}[bswnoiq][g<password>] <archive> [<filename> . . .]
  177.  
  178.     Where:   a   = add files to archive
  179.  
  180.              m   = move files to archive
  181.  
  182.              u   = update files in archive
  183.  
  184.              f   = freshen files in archive
  185.  
  186.              d   = delete files from archive
  187.  
  188.              x,e = extract files from archive
  189.  
  190.              p   = print file to screen
  191.  
  192.              l   = listing of files in archive
  193.  
  194.              t   = test archive integrity
  195.  
  196.              b   = retain backup copy of archive
  197.  
  198.              s   = suppress compression (store only)
  199.  
  200.              w   = suppress warning messages
  201.  
  202.              n   = suppress notes and comments
  203.  
  204.              o   = overwrite existing files when extracting
  205.  
  206.              i   = Use IBM PC Archive format
  207.  
  208.              q   = Use PKARC style squashing
  209.  
  210.              g   = Encrypt/decrypt archive entry
  211.  
  212.  
  213.     Written for the Archimedes by David Pilling
  214.  
  215.     Put in the Public Domain by BEEBUG V1.1 September 1988
  216.  
  217.  
  218.  
  219. Although the syntax of the ARC program may look a little frightening at first, 
  220.  
  221. it is really quite straightforward. Typically you will almost always use just 
  222.  
  223. a few of these options. The letters which appear after 'ARC', split into two 
  224.  
  225. groups; commands amufdxeplt and options bswnoiq and g. In general, you should 
  226.  
  227. have just one command letter and as many options as you need. The next section 
  228.  
  229. looks at the commands and options.
  230.  
  231. Archimedes ARC                                                          Page 4
  232.  
  233.  
  234.  
  235.  
  236. 3. ARC commands
  237.  
  238. ---------------
  239.  
  240.  
  241.  
  242. a   = add files to archive
  243.  
  244.  
  245.       This command is used to add files to an archive. If the archive does not 
  246.  
  247.       exist, it is automatically created. An example of this command is:
  248.  
  249.  
  250.           *arc a utils_arc util1 util2 util3 util4
  251.  
  252.  
  253.       This adds the files util1, util2 etc. to the archive utils_arc. You can 
  254.  
  255.       use wildcards in this command as follows:
  256.  
  257.  
  258.           *arc a my_arc b* 
  259.  
  260.  
  261.       This will add all files whose names begin with 'b' to the archive. You 
  262.  
  263.       can use any legal filename for the name of the archive, but we recommend 
  264.  
  265.       that you add the suffix '_arc' to the end of the name. This will help 
  266.  
  267.       you identify ARC files. In addition, ARC files can also be identified by 
  268.  
  269.       their filetype, which is set to &DDC (Acorn approved filetype).
  270.  
  271.  
  272.  
  273. m   = move files to archive
  274.  
  275.  
  276.       This command is like 'a' except that the files are deleted from the 
  277.  
  278.       local filing system as they are added to the archive file.
  279.  
  280.  
  281.  
  282. u   = update files in archive
  283.  
  284.  
  285.       This only adds files to the archive if the versions on disc have a more 
  286.  
  287.       recent date stamp, or if they are not already in the archive. For 
  288.  
  289.       example:
  290.  
  291.  
  292.           *arc u my_arc
  293.  
  294.  
  295.       will update all files in the current directory that have been created or 
  296.  
  297.       changed since they were last archived.
  298.  
  299.  
  300.  
  301. f   = freshen files in archive
  302.  
  303.  
  304.       This is like the 'a' command, except that files are only added if they 
  305.  
  306.       already exist in the archive with an earlier date stamp.
  307.  
  308.  
  309.  
  310. d   = delete files from archive
  311.  
  312.  
  313.       This command allows you to delete files from an archive. For example:
  314.  
  315.  
  316.           *arc d my_arc bob
  317.  
  318.  
  319.       will remove the file bob from the archive file.
  320.  
  321. Archimedes ARC                                                          Page 5
  322.  
  323.  
  324.  
  325.  
  326. x,e = extract files from archive
  327.  
  328.  
  329.       These two commands, remove files from an archive and create them in a 
  330.  
  331.       usable form on your disc. For example;
  332.  
  333.  
  334.           *arc x my_arc util1
  335.  
  336.  
  337.       recreates the file 'util1' from the archive. Notice that 'util1' remains 
  338.  
  339.       part of the archive. If you want to extract all the files, simply type:
  340.  
  341.  
  342.           *arc x my_arc
  343.  
  344.  
  345.  
  346. p   = print file to screen
  347.  
  348.  
  349.       This is very similar to 'x' and 'e' except that the file is printed out 
  350.  
  351.       on the screen, instead of being sent to the filing system.
  352.  
  353.  
  354.  
  355. l   = listing of files in archive
  356.  
  357.  
  358.       This very useful command shows you the contents of an archive along with 
  359.  
  360.       much useful information. For example, to see the contents of the archive 
  361.  
  362.       called 'my_arc', type:
  363.  
  364.  
  365.           *arc l my_arc
  366.  
  367.  
  368.       You can, of course, specify individual files or groups of files using 
  369.  
  370.       wildcards. For example:
  371.  
  372.  
  373.           *arc l my_arc pr*
  374.  
  375.  
  376.       The information displayed gives the original length of the file, 
  377.  
  378.       and how long it is in its compressed form. The time and date stamps for 
  379.  
  380.       the file and information on which form of data compression has been used 
  381.  
  382.       to store the file. You will notice that this is preceded by either 'PC' 
  383.  
  384.       or 'ARC', which indicates whether the file is stored in PC or Archimedes 
  385.  
  386.       format. 
  387.  
  388.  
  389.  
  390. t   = test archive integrity
  391.  
  392.  
  393.       A CRC (Cyclic Redundancy Check) is kept for each file added to the 
  394.  
  395.       archive, this allows ARC to tell you if a file has been corrupted. This 
  396.  
  397.       can happen when you are transferring files between different computers. 
  398.  
  399.       The 't' command unpacks all of the archive entries (without saving them 
  400.  
  401.       anywhere), and checks the CRC for each file against the recorded value. 
  402.  
  403.       It reports back to you any damage to the archive. For example, to test 
  404.  
  405.       that the archive 'my_arc' has been recieved correctly, type:
  406.  
  407.  
  408.           *arc t my_arc
  409.  
  410. Archimedes ARC                                                          Page 6
  411.  
  412.  
  413.  
  414.  
  415. b   = retain backup copy of archive
  416.  
  417.  
  418.       When you add a file to an archive, the original archive is renamed to 
  419.  
  420.       B_oldname. Normally, this is deleted after the file has been succesfully 
  421.  
  422.       added. By using the 'b' option, you can keep a copy of the original 
  423.  
  424.       archive. For example, if you wanted to add the file 'program' to the
  425.  
  426.       archive 'my_arc', but want to keep a backup copy of the archive, 
  427.  
  428.       then type:
  429.  
  430.  
  431.           *arc ab my_arc program
  432.  
  433.  
  434.       The backup archive is called 'b_my_arc'.
  435.  
  436.  
  437.  
  438. s   = suppress compression (store only)
  439.  
  440.  
  441.       This allows you to add files to the archive without compressing them.
  442.  
  443.  
  444.  
  445. w   = suppress warning messages
  446.  
  447.  
  448.       This option prevents warning messages being printed.
  449.  
  450.  
  451.  
  452. n   = suppress notes and comments
  453.  
  454.  
  455.       This option suppresses notes and comments.
  456.  
  457.  
  458.  
  459. o   = overwrite existing files when extracting
  460.  
  461.  
  462.       When you extract a file, it may be that a file with the same name 
  463.  
  464.       already exists. Normally, you will be prompted to overwrite the file. If 
  465.  
  466.       you then select N, you will be prompted for permission to rename the 
  467.  
  468.       file. If you then select Y, ARC will pick a sensible name, but if you 
  469.  
  470.       select N, ARC will continue to the next file to be extracted. The 'o' 
  471.  
  472.       option allows you to prevent all prompting, and just overwrite existing 
  473.  
  474.       files. For example:
  475.  
  476.  
  477.           *arc xo my_arc
  478.  
  479.  
  480.  
  481. i   = Use IBM PC Archive format
  482.  
  483.  
  484.       When you add a file to an archive, ARC assumes that you want the file to 
  485.  
  486.       be stored with its load and exec addresses and attributes. However, if 
  487.  
  488.       you want to give an archive to a friend with a PC, you should store the 
  489.  
  490.       files in PC format by adding the 'i' option to the command line. For 
  491.  
  492.       example, to add a PC file to an archive, type:
  493.  
  494.  
  495.           *arc ai my_arc PCprog
  496.  
  497. Archimedes ARC                                                          Page 7
  498.  
  499. q   = Use PKARC style squashing
  500.  
  501.  
  502.       Squashing is a variation on LZW coding used by the fairly popular PC
  503.  
  504.       program PKARC. By adding this option, you make ARC use squashing instead
  505.  
  506.       of crunching. You should consider that squashing will not always be
  507.  
  508.       more efficient than crunching and often will produce only small gains. 
  509.  
  510.       However, there are far more copies of ARC than PKARC, and these will not
  511.  
  512.       be able to unpack squashed archives. ARC from version 1.1, can unpack
  513.  
  514.       IBMPC archives made using PKARC and it will do this whether you set the
  515.  
  516.       q flag or not.
  517.  
  518.  
  519.  
  520. g   = Encrypt/decrypt archive entry
  521.  
  522.  
  523.       The 'g' (garble) option allows you to give a password which is used to 
  524.  
  525.       encrypt files stored in the archive. The data compression normally 
  526.  
  527.       applied will make files unreadable using *TYPE or *DUMP, this lets only 
  528.  
  529.       people who know the password extract them from the archive. For example, 
  530.  
  531.       if you wish to add 'newfile' to the archive 'my_arc', and encrypt it 
  532.  
  533.       using the password 'beebug', type:
  534.  
  535.  
  536.           *arc agbeebug my_arc newfile
  537.  
  538.  
  539.       When you want to extract the file again, you should type:
  540.  
  541.  
  542.           *arc xgbeebug my_arc newfile
  543.  
  544.  
  545.       The password can be any length, and is not case sensitive. You can if 
  546.  
  547.       you wish use different passwords for each file in an archive, but we 
  548.  
  549.       advise against it. If you should forget or mistype your password, it is 
  550.  
  551.       unlikely that you will ever recover the file.
  552.  
  553. Archimedes ARC                                                          Page 8
  554.  
  555.  
  556.  
  557.  
  558. 4. Archive file format
  559.  
  560. ----------------------
  561.  
  562. An Archive, is a binary file consisting of archive markers, archive headers 
  563.  
  564. and file data. All archives are preceded by an archive marker. This is a 
  565.  
  566. single byte of value 27.
  567.  
  568.  
  569. An archive header, consists of several bytes.
  570.  
  571.  
  572. byte  1      Header version number. This tells you how the file data is stored 
  573.  
  574.              and how many bytes there are in the header. The header version 
  575.  
  576.              numbers for the PC, are detailed below. An Archimedes header 
  577.  
  578.              version number is identical to the corresponding PC number except 
  579.  
  580.              it has bit 7 set.
  581.  
  582.  
  583. bytes 2-15   Filename
  584.  
  585.  
  586. bytes 16-19  Compressed file length
  587.  
  588.  
  589. bytes 20,21  File date stamp
  590.  
  591.  
  592. bytes 22,23  File time stamp
  593.  
  594.  
  595. bytes 24,25  CRC for the file
  596.  
  597.  
  598. bytes 26-29  If the header type is greater than 1, these hold the original 
  599.  
  600.              file length otherwise they are not present.
  601.  
  602.  
  603. bytes 30-33  If bit 7 of the header version number is set, these bytes hold 
  604.  
  605.              the Archimedes load address for the file otherwise they are not 
  606.  
  607.              present. 
  608.  
  609.  
  610. bytes 34-37  If bit 7 of the header version number is set, these bytes hold 
  611.  
  612.              the Archimedes exec address for the file otherwise they are not 
  613.  
  614.              present.
  615.  
  616.  
  617. bytes 38-41  If bit 7 of the header version number is set, these bytes hold 
  618.  
  619.              the Archimedes file attributes otherwise they are not present.
  620.  
  621.  
  622. The archive header, is followed by the file data.
  623.  
  624.  
  625. The file data is followed by another archive marker
  626.  
  627.  
  628. The archive finishes with an archive marker followed by a zero byte.
  629.  
  630.  
  631. The time and date fields are always filled in. If the file has a load and exec 
  632.  
  633. address, these are the time and date when the file was added to the archive 
  634.  
  635. otherwise, they are derived from the Archimedes datestamp. In all extract 
  636.  
  637. operations on Archimedes format archives, the contents of the load and exec 
  638.  
  639. fields take precedence.
  640.  
  641.  
  642. PC and ARC formats may be mixed in one archive for use on the Archimedes. 
  643.  
  644. Archimedes ARC                                                          Page 9
  645.  
  646.  
  647.  
  648.  
  649. PC ARC Header version numbers:
  650.  
  651.  
  652.        1 = Old style, no compression
  653.  
  654.        2 = New style, no compression
  655.  
  656.        3 = Compression of repeated characters only
  657.  
  658.        4 = Compression of repeated characters plus Huffman Squeezing
  659.  
  660.        5 = Lempel-Zev packing of repeated strings (old style)
  661.  
  662.        6 = Lempel-Zev packing of repeated strings (new style)
  663.  
  664.        7 = Lempel-Zev Welch packing with improved hash function
  665.  
  666.        8 = Dynamic Lempel-Zev packing with adaptive reset
  667.  
  668.        9 = PKARC style squashing
  669.  
  670.  
  671. The time and date stamps are two byte values from which the time in years 
  672.  
  673. etc., can be found as follows;
  674.  
  675.  
  676.        year   = (date >> 9) & 0x7f;   
  677.  
  678.        month  = (date >> 5) & 0x0f;
  679.  
  680.        day    = date & 0x1f;
  681.  
  682.  
  683.        hour   = (time >> 11) & 0x1f;  
  684.  
  685.        minute = (time >> 5)  & 0x3f;
  686.  
  687.        second = (time & 0x1f) * 2;
  688.  
  689.  
  690. Where years are offset from 1980, months begin with 1=January.
  691.  
  692. Archimedes ARC                                                          Page 10
  693.  
  694.  
  695.  
  696.  
  697. 5. ARC support
  698.  
  699. --------------
  700.  
  701. Please send any comments or suggestions for ARC to the address below. In 
  702.  
  703. addition, if you would like details of the latest version of ARC and how to 
  704.  
  705. get hold of a copy, please contact:
  706.  
  707.  
  708.     Software Manager
  709.  
  710.     Beebug Ltd.
  711.  
  712.     Dolphin Place,
  713.  
  714.     Holywell Hill,
  715.  
  716.     St. Albans,
  717.  
  718.     Herts.
  719.  
  720.     AL1 1EX
  721.  
  722.  
  723.     Tel. (0727) 40303